knitr::opts_chunk$set(eval = FALSE)
Preparation
Install usethis package
install.packages("usethis")
SSH vs. HTTPS
You can chose if you want to use SSH or HTTPS as a default protocol to communicate with the remote server. If you correctly set up SSH key authentication, you can just use SSH protocol and skip the next step. If you have not set up SSH key authentication yet or if you prefer to use HTTPS for any other reason, you need to setup a Personal Access Token (PAT).
Setup PAT to use HTTPS protocol with Github
Check if you already have a personal access token for Github
gh::gh_token()
If not, you can create one
usethis::create_github_token()
This will first open Github and ask you to sign in. Then you are asked to create a new personal access token.
On top enter a note that reminds you what this token is for (e.g. Something like “RStudio/R on HP laptop”).
You can set an expiration date if you want (it is recommended for security reasons). You can also select the scopes for your PAT. For general use case, the default selected scopes are enough. Scroll down and click on Generate token.
Copy the token to the clipboard. Careful: You will not be able to read the token again
Now register the token with git using the function:
gitcreds::gitcreds_set()
You are now prompted to paste your token into the Console.
Now your PAT should be added to the credentials. You can check it with
gh::gh_token()
Add usethis and the standard protocol to your Rprofile (optional)
If you want to load the usethis package automatically when starting R, you can add it to your .Rprofile. This way, you have all the usethis functionality available without having to load the package first.
Carful: Loading packages automatically should only be done for packages that are not used in your R scripts. Otherwise, you might forget to explicitly load the package in your script and the script breaks if you use it somewhere else.
Adding utility packages to the .Rprofile is however, very convenient.
You can open your .Rprofile file with
usethis::edit_r_profile()
Then you can add the following line, save the file and close it:
# supress messages just means that messages are not printed when loading the package
if (interactive()) {
suppressMessages(library(usethis))
}
options(
usethis.protocol = "ssh" # or "https" if you chose PAT + HTTPS
)
With this, usethis will be loaded everytime you open RStudio and you already registered the default protocol that you want to use with git (This is only relevant for the git things you do in usethis).
Step 1: Create new R project
To create a new R project for this exercise call the function:
usethis::create_project(path = "path/to/project/project_name")
This will create a folder with project_name and set up and empty RStudio project. The project will then immediately openend in a new RStudio instance. You can see that by default, the project already has some files inside (among them a .gitignore file).
Step 2: Initialize a git repository
With the project opened call the function
usethis::use_git()
You are now informed which changes will be committed. This is just the first commit that will include all the files that are in created by default and that are not in the .gitignore.
Confirm that you want to commit these files by selecting the correct number and press enter. Then agree to the first commit with the commit message “Initial commit”.
RStudio will be restarted and a the git GUI client will be added.
Can you find the Git Tab in the top right pane?
Step 3: Create a remote repository on Github
Create a new repository on Github that will be associated with you local repository.
Call the function
usethis::use_github(private = TRUE) # default is privat = FALSE
This should now open Github in the browser and bring you to a freshly created Github project that is not associated with your local repository.
Really convenient.
Step 4: Make changes
Create a new R file in your project and add some content to it.
You can just copy the following code for convenience:
# Look at the first lines of the iris dataset
head(iris)
# What is the iris dataset -> Call the help
?iris
# How many rows and columns does the data set have?
rownum <- nrow(iris)
colnum <- ncol(iris)
print(paste0("The iris dataset has ", rownum, " rows and ", colnum, " columns."))
# Some summary statistics on the iris data set
summary(iris)
# create a plot
plot(iris$Petal.Length, iris$Petal.Width,
xlab = "Petal Length",
ylab = "Petal Width",
main = "Petal Width vs Petal Length",
pch = 20,
col = ifelse(iris$Species == "setosa", "coral1",
ifelse(iris$Species == "virginica", "cyan4",
ifelse(iris$Species == "versicolor",
"darkgoldenrod2", "grey"
)
)
)
)
# add a legend
legend("bottomright", c("setosa", "virginica", "versicolor"),
col = c("coral1", "cyan4", "darkgoldenrod2"), pch = 20
)
Step 5: Commit and push the new file
In the Git Pane of RStudio, click on Diff or Commit (both buttons bring you to a similar window.)
Stage your file (i.e. git add) by checking the check box next to it. On the bottom you can see the code that you added (therefore green).
Enter a commit message on the right and click commit. When the commit is finished, close the little window that opened.
Now push the changes to Github by clicking on the green upward arrow on the top right.
Go to Github and check if everything was pushed as you expected.
Step 6: Create a new branch
In this step, you will create a new branch for a new feature that you want to introduce. This branch will later be use to do a pull request.
In RStudio, you can create a new branch, by clicking on the little violet branch symbol in the git pane:
Enter a name for your new branch (no white space in name!) and leave everything else as it is. Click on create and RStudio will create and switch branch for you. Note that now, the checked out branch is not master/main anymore but you new branch (see image above).
Step 7: Change files and push new branch to remote
Open the R file that you created in your project. Now change some of the code.
You can maybe deltete a part of it and instead add something else, like e.g.
It’s not important that the code makes sense here.
Now save the file and commit and push it again (repeat step 5 and make sure that you are not on master/main but on your new branch).
Step 8: Create a pull request
Now switch to your remote repository on Github. Github should automatically detect, that you created a new branch and will ask you to create a pull request for it. It should look something like this:
Click on Compare & pull request.
Now you can add a title and description for your pull request. This can be quite a long text if you made lots of changes that you need to explain. When you are finished click on Create pull request.
Now your (potential) collaborators can browse your code and make comments.
To see how it looks like, make a comment yourself.
On top, you can go to Files changed and see all the differences that are made in this pull request.
You can select single or multiple lines of code and add comments to it.
Just explore the functionality of pull requests a bit by yourself.